Skip to main content

GeoCoderController

The GeoCoderController provides geocoding functionality by integrating with Microsoft Azure Maps Search API to convert location names to geographic coordinates.

Overview​

This controller enables address-to-coordinates conversion for the SWMM application, allowing users to input location names and receive latitude/longitude coordinates for mapping and analysis purposes.

Data Sources​

  • External API: Microsoft Azure Maps Search API
  • No Database Storage: Stateless geocoding requests
  • Configuration: Hardcoded subscription key

Endpoints​

GET /api/geocoder/coordinates​

Converts a location name to geographic coordinates.

Query Parameters:

  • location (string): Address or location name to geocode

Response:

  • 200 OK: Returns array of coordinates [longitude, latitude]
  • Empty Array: Location not found or API error

Response Format:

[longitude, latitude]

Data Flow:

Azure Maps API Call:

GET https://atlas.microsoft.com/search/address/json?&subscription-key={key}&api-version=1.0&language=en-US&query={location}

Azure Maps Integration​

API Details​

  • Service: Azure Maps Search API
  • Version: 1.0
  • Language: en-US
  • Response Format: JSON
  • Authentication: Subscription key

Response Structure​

{
  "results": [
    {
      "position": {
        "lat": "latitude",
        "lon": "longitude"
      }
    }
  ]
}

Configuration​

Current Implementation:

  • Hardcoded subscription key: nChmDJt1_W5cjal0GghQpLlgV50sC4FLLMokqOQqoMk
  • API version: 1.0
  • Language: en-US

Recommended Configuration:

{
  "AzureMaps": {
    "SubscriptionKey": "your_subscription_key",
    "ApiVersion": "1.0",
    "Language": "en-US"
  }
}

Error Handling​

  • HTTP Exceptions: Catches and logs HttpRequestException
  • Parsing Errors: Graceful handling of malformed responses
  • Empty Results: Returns empty array for unfound locations
  • API Failures: Logs exceptions to console

Dependencies​

  • System.Net.Http
  • System.Text.Json
  • Microsoft.AspNetCore.Mvc

Usage Examples​

Request:

GET /api/geocoder/coordinates?location=Chicago, IL

Response:

[-87.6298, 41.8781]

Request:

GET /api/geocoder/coordinates?location=123 Main Street, New York, NY

Response:

[-74.006, 40.7128]

Performance Considerations​

  • Single Result: Returns only the first (most relevant) result
  • No Caching: Each request hits the Azure Maps API
  • Timeout Handling: Relies on default HTTP client timeout
  • Memory Efficient: Minimal object allocation

Security Considerations​

  1. API Key Exposure: Subscription key is currently hardcoded
  2. Input Validation: No validation of location parameter
  3. Rate Limiting: No built-in rate limiting
  4. HTTPS: Uses secure HTTPS for API calls

Limitations​

  • Returns only first result from Azure Maps
  • No support for multiple results
  • No reverse geocoding (coordinates to address)
  • No address validation or formatting
  • Hardcoded subscription key

Future Enhancements​

  1. Configuration Management: Move API key to configuration
  2. Result Caching: Implement caching for repeated requests
  3. Multiple Results: Support for multiple geocoding results
  4. Reverse Geocoding: Add coordinates-to-address functionality
  5. Input Validation: Validate and sanitize location input
  6. Error Responses: More detailed error information